package com.ruben.simplescaffold.utils.steam;

import java.util.Iterator;
import java.util.Spliterator;

/**
 * 所有类型Steam公共接口，例如引用类型、int、long、double等，该接口定义不同Steam的规范，并允许它们实现互相转换
 * 实现AutoCloseable接口，将会在try-with-resources时自动调用AutoCloseable的close函数关闭资源
 *
 * @param <T> 元素类型
 * @param <S> steam流类型
 * @author jdk
 * @see Steam
 * @see IntSteam
 * @see LongSteam
 * @see DoubleSteam
 * @since 1.8
 */
public interface BaseSteam<T, S extends BaseSteam<T, S>> extends AutoCloseable {

    /**
     * 返回流元素的迭代器，能用于遍历
     *
     * @return 流元素的迭代器
     */
    Iterator<T> iterator();

    /**
     * 返回流的拆分器，能用于并行流拆分任务等
     *
     * @return 返回流的拆分器
     */
    Spliterator<T> spliterator();

    /**
     * 返回是否并行流
     *
     * @return 是否并行流
     */
    boolean isParallel();

    /**
     * 将并行状态改为非并行，再返回该流
     *
     * @return 改为非并行流的它本身
     */
    S sequential();

    /**
     * 和上面的相反，并行状态改为并行，再返回该流
     *
     * @return 改为并行流的它本身
     */
    S parallel();

    /**
     * 将有序状态改为无序流
     * 注意无序并不是乱序，如果默认为自然排序，则不会变化元素顺序;但如果已经对元素进行sorted函数进行排序后，调用该函数能还原成原来的顺序
     * 注意和无限流以及并行流搭配使用时可能会导致结果与预期不符
     *
     * @return 返回无序流，如果已经是无序，则直接返回本身
     */
    S unordered();

    /**
     * 流关闭操作，下方的参数closeHandler允许在执行默认的流关闭执行后(哪怕)执行一些额外逻辑
     *
     * @param closeHandler 流关闭后执行额外逻辑
     * @return 返回本身，用于链式调用
     */
    S onClose(Runnable closeHandler);

    /**
     * 关闭此流，从而调用此流管道的所有关闭处理程序。
     *
     * @throws Exception 关不了的时候抛异常
     * @see AutoCloseable#close()
     */
    @Override
    void close() throws Exception;
}
